home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / HCGS / TN.HCGS.001 next >
Encoding:
Text File  |  1991-06-28  |  6.6 KB  |  232 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. HyperCard IIGS
  8. #1:          Corrections to the Script Language Guide
  9.  
  10. Written by:  Dan Strnad & Matt Deatherage                          March 1991
  11.  
  12. This Technical Note corrects the HyperCard IIgs Script Language Guide from
  13. Addison-Wesley.
  14. _____________________________________________________________________________
  15.  
  16.  
  17.  
  18. Appendix A:  External Commands and Functions
  19.  
  20. Page 317:  ReturnStat
  21.  
  22. Developers who worked with the beta version of HyperCard IIgs on Volume V of 
  23. the Developer CD (or volume 4 of Developer Essentials) should pay special 
  24. attention to the use of the returnStat parameter documented on page 317 ofthe 
  25. manual, as this method for using HyperCard's error-reporting facilities 
  26. wasnot present in beta versions of HyperCard.
  27.  
  28. Page 318:  HyperCard IIgs callbacks
  29.  
  30. Before describing the callbacks, the Script Language Guide says that thefirst 
  31. parameter to each callback is the parameter block pointer that HyperCard IIgs 
  32. passes to the XCMD or XFCN.  This is not correct; the XCMD/XFCN 
  33. parameterblock is not passed to callback routines.  Each callback uses only 
  34. the parameters supplied with its description.
  35.  
  36. Pages 318-324:  Callback descriptions
  37.  
  38. The numbers listed for each callback are actually decimal numbers, not 
  39. hexadecimal.  There should not be a "$" in front of each number.
  40.  
  41. Pages 325-330:  Beep, an example XCMD
  42.  
  43. Although there are "beep" sample XCMDs provided with the HyperCard IIgsScript 
  44. Language Guide, they do not necessarily build and execute unmodified. 
  45. Specifically, depending on your compiler, there could be a linking 
  46. problemwith the Pascal and C XCMDs as given in the manual.
  47.  
  48. XCMDs and XFCNs are code resources, and are therefore subject to the 
  49. limitations listed in Apple IIgs Technical Note #86, Risking ResourcefulCode. 
  50. The specific problem here is that most Pascal and C compilers will create at 
  51. least three segments:  ~globals, ~arrays, and main.  An XCMD or XFCN can only 
  52. have one segment and the entry point must come first.  Not only must you link 
  53. all the object segments into one segment, but you must specifically 
  54. extractthe entry point and link it first.  HyperCard will pass control to the 
  55. first byte of the loaded XCMD or XFCN, and therefore this must be the entry 
  56. point.  The samples in Appendix A point this out in the code.
  57.  
  58. Actual buildable sample source for the "beep" XCMDs is available in APW 
  59. andMPW IIgs format on Volume VI or later of the Developer CD Series (or 
  60. volume 5 or later of Developer Essentials).  A complete APW C sample is 
  61. included below.
  62.  
  63. An APW Sample XCMD:  "CBeep"
  64.  
  65. CBeep.c
  66.  
  67.  
  68. /*----------------------------------------------------------------------
  69.  
  70.   file CBeep.c
  71.  
  72.   This XCMD has the following syntax:
  73.  
  74.     CBeep       beep once
  75.     CBeep ##    beep n times
  76.     CBeep ?     display usage information
  77.     CBeep !     display version information
  78.  
  79.   Copyright Apple Computer, Inc.  1989-1991
  80.   All Rights Reserved.
  81.  
  82. ----------------------------------------------------------------------*/
  83.  
  84. #include <types.h>
  85. #include <MiscTool.h>
  86. #include <GSOS.h>
  87. #include <HyperXCMD.h>
  88.  
  89. /*
  90.     Globals
  91. */
  92.  
  93. int _toolErr;
  94. XCMDPtr gParamPtr;
  95.  
  96.  
  97. /*
  98.     Forwards
  99. */
  100. pascal void CBeep();
  101.  
  102.  
  103.  
  104. /*  We place the entry point function in its own segment, so the linker can
  105.     extract it and ensure that it's first in the load file. */
  106.  
  107. segment "EntrySeg"
  108.  
  109. /*
  110.    This is the entry point to the program.  Make sure this procedure
  111.    comes first in the final OMF resource because this is where HyperTalk
  112.    will be jumping in.
  113.  
  114.    For a really simple XCMD you could just put the code all in here, but
  115.    for cleanliness' sake this example calls another routine from here.
  116.  
  117.  
  118. */
  119. pascal void EntryPoint(paramPtr)
  120. XCMDPtr paramPtr;
  121. {
  122.   CBeep(paramPtr);
  123. }
  124.  
  125. /*  All other code & data is placed in the "Main" segment   */
  126.  
  127. segment "Main"
  128.  
  129.  
  130.  
  131. /*  The actual CBeep function.  Interpret parameters and beep the speaker   
  132. */
  133.  
  134. pascal void CBeep(paramPtr)
  135. XCMDPtr paramPtr;
  136. {
  137.   short     beepCount;
  138.   short     counter;
  139.   Str255    str;
  140.  
  141.   char  *formStr    = "\pAnswer \"FORM: CBeep {count}\"";
  142.   char  *versionStr = "\pAnswer \"CBeep XCMD v1.0\" & return & \"(c) 1991 
  143. Apple Computer, Inc.\"";
  144.  
  145.   gParamPtr = paramPtr;     /* put in a global for easy access in other funcs  
  146.  */
  147.  
  148.   if (paramPtr->paramCount > 0) {
  149.     ZeroToPas(*(paramPtr->params[0]), &str);
  150.  
  151.     beepCount = 0;
  152.  
  153.     if (str.text[0] == '?')         /* test for special characters  */
  154.       SendCardMessage(formStr);
  155.     else if (str.text[0] == '!')
  156.       SendCardMessage(versionStr);
  157.  
  158.     else beepCount = StrToNum(&str);        /* not a special - take as # of 
  159. beeps */
  160.   }
  161.   else beepCount = 1;   /* no count, assume one */
  162.  
  163.   beepCount = (beepCount <= 15) ? beepCount : 15;   /* limit 15 beeps   */
  164.  
  165.   for (counter = 0; counter < beepCount; counter++) SysBeep();
  166. }
  167.  
  168. CBeep.r
  169.  
  170. /*******************************************************************/
  171. /*
  172. /* CBeep.r
  173. /*
  174. /* Copyright (C) 1991
  175. /* Apple Computer, Inc.
  176. /* All Rights Reserved
  177. /*
  178. /* Rez source for building XCMDs.
  179. /*
  180. /*******************************************************************/
  181.  
  182. #include "types.rez"
  183.  
  184. read $801E (1, convert) "CBeep.omf";
  185.  
  186. resource rResName ($0001801E) {
  187.             1,
  188.             { 1, "CBeep";
  189.             }
  190. };
  191.  
  192. Make file
  193.  
  194. * ------------------------------------------------------------------
  195. *
  196. *  This makefile will build C XCMDs for HyperTalk
  197. *
  198. *  Copyright Apple Computer, Inc.  1991
  199. *  All Rights Reserved.
  200. *
  201. *  Builds:  CBeep
  202. *  This makefile depends on a .r file called CBeep.r to act
  203. *  as a source for the resource compiler.
  204.  
  205. compile +t +e CBeep.c keep=CBeep
  206.  
  207. * ------------------------------------------------------------------
  208. *
  209. *  The compilers will output 3 or more segments:  main, containing code;
  210. *  and ~globals and ~arrays containing data.  This line ensures that
  211. *  everything gets put back into the main segment.
  212. *
  213. *  In addition, it specifically links the EntryPoint procedure FIRST,
  214. *  ahead of any globals or data structures.
  215.  
  216. * The linker line is very long - make sure you use all of it
  217.  
  218. linkiigs -x -lseg main CBeep.root(@EntrySeg) CBeep.root(@Main) 
  219. CBeep.root(@~arrays) CBeep.root(@~globals) 2/CLib -lib 2/CLib -o CBeep.omf
  220.  
  221. compile CBeep.r keep=CBeep.rsrc
  222.  
  223. * now use your favorite resource utility to copy the XCMD from CBeep.rsrc
  224. * into your stack
  225.  
  226.  
  227. Further Reference
  228. _____________________________________________________________________________
  229.   o  HyperCard IIgs Script Language Guide
  230.   o  Apple IIgs Technical Note #86, Risking Resourceful Code
  231.   o  HyperCard IIgs Technical Note #2, Known HyperCard Bugs
  232.